/**
 * <p>The top level artifact of the Feed Object Model.  The Parser component
 * processes data from an InputStream and returns a Document instance.  The 
 * type of Document returned depends on the XML format being parsed.  The 
 * Feed Object Model supports four basic types of documents: FeedDocument,
 * EntryDocument, ServiceDocument (Atom Publishing Protocol Introspection
 * Documents) and XmlDocument (any arbitrary XML).</p>
 */
public interface Document extends Element {  
  
  /**
   * Returns the root element of the document (equivalent to DOM's getDocumentElement)
   * @return The root element of the document
   */
  Element getRoot();
  
  /**
   * Sets the root element of the document
   * @param root Set the root element of the document
   */
  Document setRoot(Element root);
  
  /**
   * Returns the Base URI of the document.  All relative URI's contained in the
   * document will be resolved according to this base.
   * @return The Base IRI
   */
  IRI getBaseUri();
  
  /**
   * Sets the Base URI of the document.  All relative URI's contained in the 
   * document will be resolved according to this base.
   * @param base The Base URI
   * @throws IRISyntaxException if the IRI is malformed 
   */
  Document setBaseUri(String base);
  
  /**
   * Returns the content type of this document
   * @return The content type of this document
   */
  Activation.MimeType getContentType();
  
  /**
   * Sets the content type for this document
   * @param contentType The content type of document
   * @throws MimeTypeParseException if the content type is malformed
   */
  Document setContentType(String contentType);
  
  /**
   * Returns the last modified date for this document
   * @return The last-modified date
   */
  Datetime getLastModified();
  
  /**
   * Sets the last modified date for this document
   * @param lastModified the last-modified date
   */
  Document setLastModified(Datetime lastModified);
  
  /**
   * Gets the charset used for this document
   * @return The character encoding used for this document
   */
  String getCharset();
  
  /**
   * Sets the charset used for this document
   * @param charset The character encoding to use
   */
  Document setCharset(String charset);
  
  /**
   * Add a processing instruction to the document
   * @param target The processing instruction target
   * @param value The processing instruction value
   */
  Document addProcessingInstruction(String target, String value);
  
  /**
   * Get the values for the given processing instruction
   */
  String[] getProcessingInstruction(String target);
  
  /**
   * Add a xml-stylesheet processing instruction to the document
   * @param href The href of the stylesheet
   * @param media The media target for this stylesheet or null if none
   */
  Document addStylesheet(String href, String media);
  
  /**
   * Return the entity tag for this document
   */
  XML.EntityTag getEntityTag();
  
  /**
   * Set the entity tag for this document
   */
  Document setEntityTag(EntityTag tag);
  
  /**
   * Set the entity tag for this document
   */
  Document setEntityTag(String tag);
  
  /**
   * Get the language
   */
  String getLanguage();
  
  /**
   * Returns the value of the xml:lang attribute as a Lang object
   */
  XML.Lang getLanguageTag();
  
  /**
   * set the base language
   */
  Document setLanguage(String lang);
  
  /**
   * Get the slug for this document
   */
  String getSlug();
  
  /**
   * Set the slug for this document
   */
  Document setSlug(String slug);
  
  /**
   * Return true if insignificant whitespace must be preserved
   */
  Boolean getMustPreserveWhitespace();

  /**
   * Set to true to preserve insignificant whitespace
   */
  Document setMustPreserveWhitespace(boolean preserve);
  
  /**
   * Get the XMLVersion used by this document
   */
  XML.XMLVersion getXmlVersion();
}
